/*
* Copyright (c) 2008, German Buela
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*     * Redistributions of source code must retain the above copyright
*       notice, this list of conditions and the following disclaimer.
*     * Redistributions in binary form must reproduce the above copyright
*       notice, this list of conditions and the following disclaimer in the
*       documentation and/or other materials provided with the distribution.
*     * The name of German Buela may not be used to endorse or promote products
*       derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY GERMAN BUELA "AS IS" AND ANY
* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL GERMAN BUELA BE LIABLE FOR ANY
* DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

package org.gbuela.avant;

import java.util.Map;

/**
 * Through this interface, a CommandContext provides access to request specific data.
 * @see org.gbuela.avant.http.HttpRequest
 * @author gbuela
 */
public interface Request {
    /**
     * Returns an attribute from either the request, session or servlet context (whichever
     * is found first, in that order, or null if not found).
     * @param name attribute name
     * @return the attribute of that name
     */
    public Object getAttribute(String name);
    /**
     * Sets (or removes) an attribute in the request scope.
     * @param name attribute name
     * @param value attribute value (if null, the attribute is removed from the scope)
     */
    public void setAttribute(String name, Object value);
    /**
     * Returns an attribute from the session scope.
     * @param name attribute name
     * @return the attribute of that name
     */
    public Object getSessionAttribute(String name);
    /**
     * Sets (or removes) an attribute in the session scope.
     * @param name attribute name
     * @param value attribute value (if null, the attribute is removed from the scope)
     */
    public void setSessionAttribute(String name, Object value);
    /**
     * Returns an attribute from the global (servlet context) scope.
     * @param name attribute name
     * @return the attribute of that name
     */
    public Object getGlobalAttribute(String name);
    /**
     * Sets (or removes) an attribute in the global (servlet context) scope.
     * @param name attribute name
     * @param value attribute value (if null, the attribute is removed from the scope)
     */
    public void setGlobalAttribute(String name, Object value);
    /**
     * Returns a request parameter.
     * @param name parameter name
     * @return the parameter of that name
     */
    public String getParameter(String name);
    /**
     * Returns the request parameters.
     * @return a Map with all request parameters.
     */
    public Map getParameterMap();
    /**
     * Returns the request's context path.
     * @return context path
     */
    public String getContextPath();
    /**
     * Returns the request URL as issued by the client.
     * @return request URL
     */
    public String getRequestURL();
    
    /**
     * Returns the underlying servlet request object. 
     * Note: It is recommended to NOT rely on this object for anything, 
     * if possible, in order to allow for easy command testing.
     * @return the underlying servlet request object that this interface wraps
     */
    public javax.servlet.ServletRequest getServletRequest();
}
